Repository navigation
Docs: Add PHPStan array shapes - #13894
swissspidy wants to merge 9 commits into
Conversation
Adds array shapes and refined array types to functions that return or accept arrays with a known set of keys. The HTTP response is defined once, as the `HTTP_Response` type on `WP_Http`, and repeated on the `wp_remote_*()` and `wp_safe_remote_*()` functions. It includes the response of a non-blocking request, which has no `filename` and `false` for the code and message. Compared to the function map in php-stubs/wordpress-stubs, `WP_Widget::widget()` requires only the four keys `the_widget()` passes, `wp_widget_rss_form()` accepts the `'__i__'` placeholder as the widget number, the script tag attributes accept `false`, and `get_shortcode_tags_in_content()` returns `list<string>`. The map's `list<mixed>` for cron arguments, its shapes for `WP_List_Table::set_pagination_args()` and `Custom_Image_Header::set_header_image()`, and its conditional return for `get_block_wrapper_attributes()` are left out, since core does not match them. See #65817. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VieGtSQtUoVfHiGwTmkvtc
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. Props Bot commandsYou can trigger Props Bot actions by commenting on this PR:
|
Test using WordPress PlaygroundThe changes in this pull request can previewed and tested using a WordPress Playground instance. WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser. Some things to be aware of
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Several new shapes exclude valid RSS widget inputs and short-circuited HTTP responses.
Review effort: Balanced
Findings: 3
Open (3)
What changed in this PR
Adds refined PHPStan array types and shapes across WordPress APIs without changing runtime behavior.
Changes:
- Defines reusable and public HTTP response shapes.
- Refines widget, robots, navigation, media, and block attribute arrays.
- Narrows several utility return and parameter types.
| File | Description |
|---|---|
src/wp-includes/widgets.php |
Types RSS widget data. |
src/wp-includes/shortcodes.php |
Types shortcode lists. |
src/wp-includes/script-loader.php |
Types script attributes. |
src/wp-includes/robots-template.php |
Types robots directives. |
src/wp-includes/nav-menu.php |
Types menu registrations. |
src/wp-includes/http.php |
Types remote responses. |
src/wp-includes/functions.php |
Refines unique-ID input. |
src/wp-includes/formatting.php |
Types HTML split results. |
src/wp-includes/feed.php |
Types Atom text tuples. |
src/wp-includes/class-wp-widget.php |
Shapes widget display arguments. |
src/wp-includes/class-wp-http.php |
Defines the HTTP response alias. |
src/wp-includes/class-wp-dependencies.php |
Refines dependency groups. |
src/wp-includes/class-wp-block-supports.php |
Types wrapper attributes. |
src/wp-admin/includes/post.php |
Types status lists. |
src/wp-admin/includes/nav-menu.php |
Shapes menu columns. |
src/wp-admin/includes/ms.php |
Shapes help-tab arguments. |
src/wp-admin/includes/media.php |
Shapes media helper results. |
src/wp-admin/includes/list-table.php |
Shapes list-table arguments. |
src/wp-admin/includes/bookmark.php |
Refines bookmark results. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
🤖 Comment by Claude Opus 5.5 Props for this subset, gathered from the full history of
Props for this PR (swissspidy for the split, westonruter for the review that shaped it): Generated by Claude Code |
Make http_response optional in the HTTP response shapes, since a pre_http_request filter can return a response without it. In wp_widget_rss_form(), make error optional and allow 'hidden' for the inputs, matching what the function handles. Add the documented plural, singular and ajax keys to the _get_list_table() shape, and drop two @phpstan-param tags that repeated the canonical ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015BuoHZQvJMvPEYp4Sfjgvd
Resolve the conflict in get_block_wrapper_attributes() by taking trunk's version, which already documents $extra_attributes as array<string, string|int|float>. Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com>
| * @var (int|false)[] | ||
| * | ||
| * @phpstan-var array<string, int|false> |
There was a problem hiding this comment.
Since wp_register_script() is typed as $handle being non-empty-string, I I should think that this would be appropriate here. And the non-PHPStan anotation can be updated as well:
| * @var (int|false)[] | |
| * | |
| * @phpstan-var array<string, int|false> | |
| * @var array<string, int|false> | |
| * | |
| * @phpstan-var array<non-empty-string, int|false> |
| * | ||
| * @phpstan-return array{ | ||
| * _title: string, | ||
| * cb: '<input type="checkbox" />', |
There was a problem hiding this comment.
This seems overly specific.
| * cb: '<input type="checkbox" />', | |
| * cb: non-falsy-string, |
| * | ||
| * @return array Help tab arguments. | ||
| * | ||
| * @phpstan-return array{id: 'overview', title: string, content: non-falsy-string} |
There was a problem hiding this comment.
Maybe overly specific.
| * @phpstan-return array{id: 'overview', title: string, content: non-falsy-string} | |
| * @phpstan-return array{id: non-falsy-string, title: string, content: non-falsy-string} |
| * | ||
| * @return stdClass Default link object. | ||
| * | ||
| * @phpstan-return object{link_url: string, link_name: string, link_visible: 'Y'}&stdClass |
There was a problem hiding this comment.
This doesn't seem be working. At the return statement I'm getting a PHPStan error still:
Function get_default_link_to_edit() should return object{link_url: string, link_name: string, link_visible: 'Y'}&stdClass but returns stdClass.
| * @param int $link_id Link ID to look up. | ||
| * @return int[]|WP_Error The IDs of the requested link's categories, or else a WP_Error if the `link_category` taxonomy was unregistered. | ||
| * | ||
| * @phpstan-return array<int, int<1, max>>|WP_Error |
There was a problem hiding this comment.
This doesn't seem to be right. It should be:
| * @phpstan-return array<int, int<1, max>>|WP_Error | |
| * @phpstan-return int[]|WP_Error |
This is the same as is presently being returned. It can't be array<positive-int> because wp_get_object_terms() returns int[]|WP_Error for fields=>ids.
| * | ||
| * @phpstan-template T of WP_List_Table | ||
| * @phpstan-param class-string<T> $class_name | ||
| * @phpstan-param array{plural?: string, singular?: string, ajax?: bool, screen?: string|WP_Screen|null} $args |
There was a problem hiding this comment.
This seems redundant with the array hash notation.
| * @phpstan-param array{plural?: string, singular?: string, ajax?: bool, screen?: string|WP_Screen|null} $args |
| * | ||
| * @param string[] $locations Associative array of menu location identifiers (like a slug) and descriptive text. | ||
| * | ||
| * @phpstan-param array<string, string> $locations |
There was a problem hiding this comment.
This is standard PHPDoc so it can be used above for the @param.
| * | ||
| * @phpstan-param array<string, bool|string> $robots | ||
| * @phpstan-return array<string, bool|string> |
There was a problem hiding this comment.
Standard PHPDoc which can be used in @param and @return.
There was a problem hiding this comment.
Same for below changes as well.
- Use standard PHPDoc generic array types in `@param` and `@return` for the robots functions and register_nav_menus(), instead of separate `@phpstan-` tags. - Key WP_Dependencies::$groups by `non-empty-string`, matching the type of the script and style handles, and update its `@var` to match. - Make the column and help tab shapes less specific. - Drop the `@phpstan-param` for _get_list_table(), which duplicates its hash notation. - Drop the `@phpstan-return` for get_default_link_to_edit(), since PHPStan does not track the properties assigned to a new stdClass instance, and for wp_get_link_cats(), since wp_get_object_terms() returns `int[]|WP_Error` for `fields` set to `ids`. Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com>
westonruter
left a comment
There was a problem hiding this comment.
Just a minor suggestion for narrowing, but otherwise LGTM
…sensitive_page(). Both always add `noindex`, and wp_robots_sensitive_page() always adds `noarchive`. The `follow` or `nofollow` directive that wp_robots_no_robots() adds is left out of its shape, since PHPStan loses the keys set in each branch when it merges them. Co-authored-by: Pascal Birchler <pascal.birchler@gmail.com>
✅ PHPStan Static AnalysisAll errors reported by PHPStan were resolved as of f622a04. Resolved errors (1)
|
…into fix/phpstan-array-shapes
|
With #13894 (comment), happy to see the level 10 strict checking working! (It was confusing at first however, because it was being reported on the PR for the strict analysis which was merged in |

Split out of #13530, as proposed in this comment (subset 7).
This adds array shapes and refined array types to functions that return or accept arrays with a known set of keys:
WP_Widget::widget()'s$args_get_list_table()'s$argswp_html_split()register_nav_menus()get_block_wrapper_attributes()'s$extra_attributesChanges from #13530
These follow the review analysis:
HTTP_Responsetype alias onWP_Http, and used byrequest(),get(),post()andhead(). The 8wp_remote_*()andwp_safe_remote_*()functions repeat it, because function docblocks cannot import a class type alias. The shape now covers non-blocking requests, which return empty headers,falsefor the code and message, nofilename, and anullhttp_response. It also matches the hash notationrequest()already has.WP_Widget::widget()$args. Only the four keys thatthe_widget()passes are required:before_widget,after_widget,before_titleandafter_title.wp_widget_rss_form().numberisint|string, since the widget template passes'__i__'.get_shortcode_tags_in_content()returnslist<string>, since it yields''when no shortcodes are registered.get_block_wrapper_attributes().$extra_attributesalso accepts numbers, which the body casts. The conditional return type is dropped, because the function can still return''when$extra_attributesis non-empty.list<mixed> $argson the cron functions. The stored cron arrays are stillarray<mixed>, sowp-cron.phpwould report errors.WP_List_Table::set_pagination_args(), which rejected numeric-string totals, the documentedinfinite_scrollkey and query strings, and forCustom_Image_Header::set_header_image(), whose body accepts objects and missing keys.@phpstan-return voidtags onwp_widget_rss_form()andregister_widget().Changes after review
http_responseis optional in all 9 shapes, becauserequest()returns apre_http_requestfilter value as is, and that value doesn't have to include it.wp_widget_rss_form().erroris optional, since the dashboard widget's first render passes onlynumber. The$inputsvalues arebool|'hidden', since'hidden'outputs a hidden field._get_list_table(). The shape includes the documentedplural,singularandajaxkeys, not justscreen.@phpstan-paramtags onwp_get_script_tag()andwp_get_inline_script_tag(), which repeated the canonicalarray<string, string|bool>already on trunk.Effect on the analysis
composer run phpstanpasses with no baseline changes. At level 10, compared against trunk, 57 errors are fixed and 19 are introduced. 2 of the 19 are inWP_Http::request(), where thepre_http_requestandhttp_responsefilters returnmixed. The rest are mostly callers that pass a plainarraywhere a shape is now expected, or existing errors reworded. (These counts were measured before the changes after review.)Trac ticket: https://core.trac.wordpress.org/ticket/66739
Use of AI Tools
AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Splitting #13530 by tag kind, applying the corrections from the review analysis on #13530 and from review on this PR, checking each subset with
composer run phpstan(also at level 10, compared against trunk) andphpcs, and drafting the commit messages and this description. Reviewed by me.This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
🤖 Generated with Claude Code
https://claude.ai/code/session_015BuoHZQvJMvPEYp4Sfjgvd